NCDUMP(1) UNIDATA UTILITIES NCDUMP(1)
NAME
ncdump - Convert netCDF files to ASCII form (CDL)
SYNOPSIS
ncdump [-c] [-h] [-v var1,...] [-b lang] [-f lang] [-l len]
[-n name] [-d f_digits[,d_digits]] file
DESCRIPTION
ncdump generates an ASCII representation of a specified
netCDF file on standard output. The ASCII representation is
in a form called CDL (``network Common Data form Language'')
that can be viewed, edited, or serve as input to ncgen.
ncgen is a companion program that can generate a binary
netCDF file from a CDL file. Hence ncgen and ncdump can be
used as inverses to transform the data representation
between binary and ASCII representations. See ncgen for a
description of CDL and netCDF representations.
ncdump defines a default format used for each type of netCDF
data, but this can be changed if a `C_format' attribute is
defined for a netCDF variable. In this case, ncdump will
use the `C_format' attribute to format each value. For ex-
ample, if floating-point data for the netCDF variable `Z' is
known to be accurate to only three significant digits, it
would be appropriate to use the variable attribute
Z:C_format = "%.3g"
ncdump may also be used as a simple browser for netCDF data
files, to display the dimension names and sizes; variable
names, types, and shapes; attribute names and values; and
optionally, the values of data for all variables or selected
variables in a netCDF file.
OPTIONS
-c Show the values of coordinate variables (variables that
are also dimensions) as well as the declarations of all
dimensions, variables, and attribute values. Data
values of non-coordinate variables are not included in
the output. This is the most suitable option to use
for a brief look at the structure and contents of a
netCDF file.
-h Show only the header information in the output, that is
the declarations of dimensions, variables, and attri-
butes but no data values for any variables. The output
is identical to using the -c option except that the
values of coordinate variables are not included. (At
most one of -c or -h options may be present.)
-v var1,...,varn
The output will include data values for the specified
Printed: 97-12-16 Last change: 1996-03-26 1
NCDUMP(1) UNIDATA UTILITIES NCDUMP(1)
variables, in addition to the declarations of all di-
mensions, variables, and attributes. One or more vari-
ables must be specified by name in the comma-delimited
list following this option. The list must be a single
argument to the command, hence cannot contain blanks or
other white space characters. The named variables must
be valid netCDF variables in the input-file. The de-
fault, without this option and in the absence of the -c
or -h options, is to include data values for all vari-
ables in the output.
-b lang
A brief annotation in the form of a CDL comment (text
beginning with the characters ``//'') will be included
in the data section of the output for each `row' of
data, to help identify data values for multidimensional
variables. If lang begins with `C' or `c', then C
language conventions will be used (zero-based indices,
last dimension varying fastest). If lang begins with
`F' or `f', then Fortran language conventions will be
used (one-based indices, first dimension varying
fastest). In either case, the data will be presented
in the same order; only the annotations will differ.
This option is useful for browsing through large
volumes of multidimensional data.
-f lang
Full annotations in the form of trailing CDL comments
(text beginning with the characters ``//'') for every
data value (except individual characters in character
arrays) will be included in the data section. If lang
begins with `C' or `c', then C language conventions
will be used (zero-based indices, last dimension vary-
ing fastest). If lang begins with `F' or `f', then
Fortran language conventions will be used (one-based
indices, first dimension varying fastest). In either
case, the data will be presented in the same order;
only the annotations will differ. This option may be
useful for piping data into other filters, since each
data value appears on a separate line, fully identi-
fied.
-l len
Changes the default maximum line length (80) used in
formatting lists of non-character data values.
-n name
CDL requires a name for a netCDF data set, for use by
ncgen -b in generating a default netCDF file name. By
default, ncdump constructs this name from the last com-
ponent of the pathname of the input netCDF file by
stripping off any extension it has. Use the -n option
Printed: 97-12-16 Last change: 1996-03-26 2
NCDUMP(1) UNIDATA UTILITIES NCDUMP(1)
to specify a different name. Although the output file
name used by ncgen -b can be specified, it may be wise
to have ncdump change the default name to avoid inad-
vertantly overwriting a valuable netCDF file when using
ncdump, editing the resulting CDL file, and using ncgen
-b to generate a new netCDF file from the edited CDL
file.
-d float_digits[,double_digits]
Specifies default number of significant digits to use
in displaying floating-point or double precision data
values for variables that don't have a `C_format' at-
tribute. Floating-point data will be displayed with
float_digits significant digits. If double_digits is
also specified, double-precision values will be
displayed with that many significant digits. If a
variable has a `C_format' attribute, that overrides any
specified floating-point default. In the absence of
any -d specifications, floating-point and double-
precision data are displayed with 7 and 15 significant
digits respectively. CDL files can be made smaller if
less precision is required. If both floating-point and
double-presision precisions are specified, the two
values must appear separated by a comma (no blanks) as
a single argument to the command. If you really want
every last bit of precision from the netCDF file
represented in the CDL file for all possible floating-
point values, you will have to specify this with -d
9,17 (according to Theorem 15 of the paper listed under
REFERENCES).
EXAMPLES
Look at the structure of the data in the netCDF file
`foo.nc':
ncdump -c foo.nc
Produce an annotated CDL version of the structure and data
in the netCDF file `foo.nc', using C-style indexing for the
annotations:
ncdump -b c foo.nc > foo.cdl
Output data for only the variables `uwind' and `vwind' from
the netCDF file `foo.nc', and show the floating-point data
with only three significant digits of precision:
ncdump -v uwind,vwind -d 3 foo.nc
Produce a fully-annotated (one data value per line) listing
of the data for the variable `omega', using Fortran conven-
Printed: 97-12-16 Last change: 1996-03-26 3
NCDUMP(1) UNIDATA UTILITIES NCDUMP(1)
tions for indices, and changing the netCDF dataset name in
the resulting CDL file to `omega':
ncdump -v omega -f fortran -n omega foo.nc > Z.cdl
REFERENCES
What Every Computer Scientist should Know About Floating-
Point Arithmetic, D. Goldberg, ACM Computing Surveys, Vol.
23, No. 1, March 1991, pp. 5-48.
SEE ALSO
ncgen(1), netcdf(3)
BUGS
Character arrays that contain a null-byte are treated like C
strings, so no characters after the null byte appear in the
output.
Multidimensional character string arrays are not handled
well, since the CDL syntax for breaking a long character
string into several shorter lines is weak.
There should be a way to specify that the data should be
displayed in `record' order, that is with the all the values
for `record' variables together that have the same value of
the record dimension.
Printed: 97-12-16 Last change: 1996-03-26 4
⌐ 1994 Man-cgi 1.15, Panagiotis Christias <christia@theseas.ntua.gr>